home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d12 / c_dates2.arc / C_DATES.DOC < prev    next >
Text File  |  1991-01-10  |  9KB  |  183 lines
  1.     - Hi there -
  2.  
  3.          Finally, there is a quick and easy way to manipulate dates in
  4.     the "C" programming  language;  that  is  what this package is all
  5.     about.
  6.  
  7.          The "C"  programming language  is,  in  this  authors  humble
  8.     opinion, the best programming language ever invented by man. Among
  9.     its weaker points,  however, is its inability ( at  least  in  its
  10.     most basic form ) to handle any sort of date variable.  This is an
  11.     important capability in  most  business  applications, which still
  12.     constitutes the majority of the programming effort in America, and
  13.     yet there hasn't been ( until now  )  an acceptable way of dealing
  14.     with this problem.  This has always struck me as  somewhat  of  an
  15.     injustice to the power of "C", so I decided to write a library for
  16.     the general public that would "do the trick".
  17.  
  18.          Manipulating dates in an effective manner involves converting
  19.     what we normally  think  of  as a "date" into a single number that
  20.     represents the number of days since  some arbitrary point in time.
  21.     For these routines, that arbitrary point in time is simply January
  22.     0, year 0000.   January  2nd,  year  0000, for example,  would  be
  23.     represented as the number 2, January 3rd, year 0000, as the number
  24.     3, and so  on.  Once the conversion is performed, calculating such
  25.     things as the day of the week, or  the  number of days between two
  26.     dates, becomes possible.
  27.  
  28.          This numerical  representation  of  a  date   is  called  the
  29.     "julian" representation, and  the  proper  name  of the equivalent
  30.     colloquial date, ie: one expressed  in terms of the month, day and
  31.     year, is called the "gregorian" representation.   These  names are
  32.     worth remembering, as  the documentation in this package refers to
  33.     all dates as either one or the other.
  34.  
  35.          All of the routines in this  library,  with  the exception of
  36.     the actual conversion  routines  themselves, manipulate  only  the
  37.     julian form of the date, the idea being that to manipulate a date,
  38.     the user first  converts  it  to  a  number, performs the required
  39.     calculations, then converts it back  to the readable ( gregorian )
  40.     form.
  41.  
  42.          There are only nine functions in this library, three of which
  43.     are implemented as rather trivial macros.  With these  nine, it is
  44.     hoped that the  user  can  accomplish  almost  any  kind  of  date
  45.     calculation required.  The names  and a brief description of these
  46.     functions are as follows:
  47.  
  48.     compiled functions:
  49.     ======== =========
  50.  
  51.     gtoj    -  to convert gregorian dates to julian dates
  52.     jtog    -  to convert julian dates to gregorian dates
  53.     dow     -  to find the numerical day of the week from a julian
  54.                date
  55.     fulldte -  to express a julian date as a verbose gregorian date
  56.     daycnt  -  to compute the days between two dates, with or without
  57.                weekends
  58.     newdate -  to compute a new date by adding or subtracting
  59.                weekdays, weekends, or both
  60.  
  61.     macro functions:
  62.     ===== =========
  63.  
  64.     suncnt  -  to  compute the number of Sundays occurring between two
  65.                julian dates.
  66.     satcnt  -  to compute the number  of  Saturdays  occurring between
  67.                two julian dates.
  68.     wkend   -  to  find the week-ending date ( ie:  the  date  of  the
  69.                following Saturday ) for a given julian date.
  70.  
  71.          I have not included any of the fancier stuff, such as perhaps
  72.     a macro that  calculates  the  date for Thanksgiving for any given
  73.     year, for that,  I think, is best  left  up  to  the  user  as  an
  74.     exercise.
  75.  
  76.          For a  full  description  of  each  of  the   above  compiled
  77.     functions, please refer  to  the  source  file, "C_dATES.C", where
  78.     each particular module's code is  prefaced  by  a  collection of C
  79.     comment lines containing the associated usage summary.
  80.  
  81.          The macro  functions  are  documented  at  the  end  of  this
  82.     document, in what I have called "Appendix A".
  83.  
  84.          These routines   can   handle   any   date,   regardless   of
  85.     chronological magnitude, from January  1st,  year 0000 to December
  86.     31st, 9999, and the source ( included ) for these  routines can be
  87.     re-compiled using any  ANSI  C compiler, on virtually any machine.
  88.     The jtog and fulldte functions,  however,  assume  an  ASCII based
  89.     machine, but the  source can easily be modified to  employ  almost
  90.     any type of character set ( with maybe a little forethought... ).
  91.  
  92.          The actual  object  module library that is included with this
  93.     package, "C_dATES.LIB", was  created   using   the   Microsoft   C
  94.     compiler, version 4.0.  There is no particular reason for choosing
  95.     this particular implementation, other than the fact that it is the
  96.     one that I use all the time.  ( It is actually quite good )
  97.  
  98.          With this package I have also included two example  programs,
  99.     written in MSC  v 4.0, that employ most of the functions contained
  100.     in this library, so that the user  can  get a feel for some of the
  101.     practical applications of these functions.  The name  of the first
  102.     program is "DAYS.EXE",  and  all  it  does, really, is compute the
  103.     days that exist between the two dates  input  on the command line.
  104.     The second program,  called "NDATE.EXE", simply returns a new date
  105.     that is computed using a start date and adding a number of days of
  106.     a specified type.   For  an  more  detailed  explanation  of their
  107.     usage, simply type in their respective names with no parameters.
  108.  
  109.          Should  you   have  any  questions,   comments,  suggestions,
  110.     contributions, expletives, marriage proposals, or hate mail, I can
  111.     be reached at my home address, 2752 Twin Brooks Dr.,  apartment 4,
  112.     Atlanta, GA  30319, (  via  U.S.  mail!  )  or alternatively,  you
  113.     can leave a message  for  me  at  one  or  more of  the  following
  114.     public BBS's:
  115.  
  116.          AESC BBS                   (404) 448-2895   2400-N-8-1
  117.          The Bird's Nest            (404) 751-0252   1200-N-8-1
  118.          The Right Place            (404) 476-2607   2400-N-8-1
  119.  
  120.          You will need to know my name;  it's James Seed...
  121.  
  122.                             A P P E N D I X   A
  123.                             ===================
  124.  
  125.                          - Macro Function Usage -
  126.                            ====================
  127.  
  128.  
  129.     suncnt( julian1, julian2 )  -  this function returns the number of
  130.                                    Sundays that  exist between the two
  131.                                    julian  dates input, expressed as a
  132.                                    signed long  integer.    The  input
  133.                                    types are as follows:
  134.  
  135.                                    julian1  -  unsigned  long  integer
  136.                                                julian date
  137.                                    julian2  -  unsigned  long  integer
  138.                                                julian date
  139.  
  140.     satcnt( julian1, julian2 )  -  this function returns the number of
  141.                                    Saturdays that  exist  between  the
  142.                                    two julian  dates  input, expressed
  143.                                     as  a  signed  long  integer.  The
  144.                                    input types are as follows:
  145.  
  146.                                    julian1  -  unsigned  long  integer
  147.                                                julian date
  148.                                    julian2  -  unsigned  long  integer
  149.                                                julian date
  150.  
  151.     wkend( julian )  -  this  function  finds  the  week-ending  date,
  152.                         expressed as an unsigned long  integer  julian
  153.                         Saturday,  that  represents   the   week  that
  154.                         includes the unsigned long julian date input.
  155.  
  156.                             A P P E N D I X   B
  157.                             ===================
  158.  
  159.                            - Revision History -
  160.                              ================
  161.  
  162.  
  163.     04/01/87  --  Original Release.
  164.  
  165.     04/01/88  --  Version 2  --  The  C_dates library  included is now
  166.                                  compatible with Turbo C ver 1.00, and
  167.                                  Microsoft C ver 4.0 & 5.0.
  168.                              --  fixed bug in the "jtog" function that
  169.                                  erroneously  returned  February  29th
  170.                                  instead of  March 1st  for particular
  171.                                  non-leap years.
  172.                  --  Added the source and .COM of a "TEST"
  173.                  program.
  174.                              --  Added  separately  compilable  source
  175.                                  modules in an included .ARC file.
  176.  
  177.  
  178.  
  179.     *** IMPORTANT NOTE ***
  180.  
  181.     The author assumes  no  responsibility  for  any  loss  or  damage
  182.     arising out of the use, misuse, or inability to use this product.
  183.